<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
   <link rel="stylesheet" type="text/css" href="stylesheet.css"/>
   <script type="text/javascript" src="js/pageToc.js"></script>
   <script type="text/javascript" src="js/sh/scripts/shCore.js"></script>
   <script type="text/javascript" src="js/sh/scripts/shBrushJScript.js"></script>
   <script type="text/javascript" src="js/sh/scripts/shBrushPhp.js"></script>
   <script type="text/javascript" src="js/sh/scripts/shBrushPlain.js"></script>
   <script type="text/javascript" src="js/sh/scripts/shBrushXml.js"></script>
   <link type="text/css" rel="stylesheet" href="js/sh/styles/shCore.css"/>
   <link type="text/css" rel="stylesheet" href="js/sh/styles/shThemeDefault.css"/>
   <script type="text/javascript">
   		SyntaxHighlighter.config.clipboardSwf = 'js/sh/scripts/clipboard.swf';
   		SyntaxHighlighter.all();
   </script>
   <title>Handling Input</title>
</head>
<body>

   <h1>Handling Input</h1>
   
   <p>Flash has a lot of powerful input handling capabilities, but they tend to be too much for a game. The InputManager and InputMap classes work together to provide a few focused capabilities to make it simple to implement controls for your game.</p>
   
   <p>Note that for general UI building tasks, you will want to use the normal Flash events.</p>
   
   <div id="pageToc"></div>

   <div id="contentArea">
   
   <h2>InputManager and InputMap</h2>
   
   <p>The InputManager is a clearing house for input events. Mostly, InputMap instance subscribe to it, although your code can do that as well. It also tracks if keys are down, so you can write code like:</p>
   
   <pre class="brush: js">
   if(InputManager.isKeyDown(InputKey.UP))
      moveItemUp();
   </pre>
   
   <p>However, this idiom generally results in brittle, complicated input handling code. A much better option is to use an InputMap, which lets you expose named input events you want to bind, and configure what keys should trigger them. That way if you want to allow users to reconfigure what keys they use, you can do so without having to modify your code.</p>
   
   <p>InputMap also lets you handle input in a uniform way. You simply provide it with input names, and callback functions that take a single numerical parameter. Digital inputs (buttons) will be called back with 0 or 1 based on if the button is up or down. Analog inputs (mouse) will be called back with the change in position of the input. In most cases this means you can write code that handles buttons or mouse input identically.</p>
   
   <p>In addition, the InputManager gives you an opportunity to handle more exotic input sources in a consistent manner. You might extend it to use a 3rd party utility to handle joystick or Wiimote input events - these would simply be exposed as other input options that can be selected when configuring the InputMap.</p>
   
   <p>The following is source code for a simple component that handles input using an InputMap:</p>
   
   <pre class="brush: js">
   public class MyInputHandlingComponent extends TickedComponent
   {
      public function get input():InputMap
      {
         return _inputMap;
      }
      
      public function set input(value:InputMap):void
      {
         _inputMap = value;
         
         if (_inputMap != null)
         {
            _inputMap.addBinding("GoLeft", _onLeft);
            _inputMap.addBinding("GoRight", onRight);
         }
      }

      public override function onTick(tickRate:Number):void
      {
         // Normally you would update your position based on this; for simplicity
         // we just print the direction we are being indicated to move.
         var direction:Number = right - left;
         Logger.print(this, "I am moving " + direction);
      }
      
      private function onLeft(value:Number):void
      {
         left = value;
      }

      private function onRight(value:Number):void
      {
         right = value;
      }
      
      
      private var _inputMap:InputMap;
      private var _left:Number = 0;
      private var _right:Number = 0;
   }
   </pre>
   
   <p>And here is the level XML to set it up as part of an entity. Notice that you specify the inputs as part of the level, making it easy to support multiple players on the same keyboard or other customizations of input.</p>
   
   <pre class="brush: xml">
   &lt;entity name="InputHandlingEntity"&gt;
      &lt;component class="MyInputHandlingComponent" name="Input"/&gt;
         &lt;Input&gt;
            &lt;!-- These correspond to the calls to AddBinding above. --&gt;
            &lt;GoLeft&gt;LEFT&lt;/GoLeft&gt;
            &lt;GoRight&gt;RIGHT&lt;/GoRight&gt;
         &lt;/Input&gt;
      &lt;/component&gt;
   &lt;/entity&gt;
   </pre>
   
   <p>Notice that you could also bind to mouse movement by doing the following:</p>
   
   <pre class="brush: xml">
   &lt;entity name="MouseInputHandlingEntity"&gt;
      &lt;component class="MyInputHandlingComponent" name="Input"/&gt;
         &lt;Input&gt;
            &lt;!-- These correspond to the calls to AddBinding above.  Only GoLeft needs to be bound because MOUSE_X gives negative as well as positive results. --&gt;
            &lt;GoLeft&gt;MOUSE_X&lt;/GoLeft&gt;
         &lt;/Input&gt;
      &lt;/component&gt;
   &lt;/entity&gt;
   </pre>
   
   <p>That's all there is to know about InputMap and InputManager! The rest of this chapter is a reference to the supported key names for InputMap.</p>

   <h2>InputMap Key Names</h2>
   
   <p>This section lists all the keys that can be used with the InputMap class. The label for each key is used both as the name of the constant in the InputKey class and the name to use when defining an InputMap in XML. Additionally, some keys may have one or more aliases listed in parentheses. For the most part these exist to provide compatibility with the names that Flash uses in the flash.ui.Keyboard class. All names are case-insensitive.</p>
   
   <h3>Navigation Keys</h3>
   
   <ul>
      <li><b>PAGE_UP</b><br/>The page up key.</li>
      <li><b>PAGE_DOWN</b><br/>The page down key.</li>
      <li><b>END</b><br/>The end key.</li>
      <li><b>HOME</b><br/>The home key.</li>
      <li><b>LEFT (LEFT_ARROW)</b><br/>The left arrow key.</li>
      <li><b>RIGHT (RIGHT_ARROW)</b><br/>The right arrow key.</li>
      <li><b>UP (UP_ARROW)</b><br/>The up arrow key.</li>
      <li><b>DOWN (DOWN_ARROW)</b><br/>The down arrow key.</li>
   </ul>
   
   <h3>Number Keys</h3>
   
   <ul>
      <li><b>ZERO (0, NUMBER_0)</b><br/>The '0' key at the top of the keyboard (not the number pad).</li>
      <li><b>ONE (1, NUMBER_1)</b><br/>The '1' key at the top of the keyboard (not the number pad).</li>
      <li><b>TWO (2, NUMBER_2)</b><br/>The '2' key at the top of the keyboard (not the number pad).</li>
      <li><b>THREE (3, NUMBER_3)</b><br/>The '3' key at the top of the keyboard (not the number pad).</li>
      <li><b>FOUR (4, NUMBER_4)</b><br/>The '4' key at the top of the keyboard (not the number pad).</li>
      <li><b>FIVE (5, NUMBER_5)</b><br/>The '5' key at the top of the keyboard (not the number pad).</li>
      <li><b>SIX (6, NUMBER_6)</b><br/>The '6' key at the top of the keyboard (not the number pad).</li>
      <li><b>SEVEN (7, NUMBER_7)</b><br/>The '7' key at the top of the keyboard (not the number pad).</li>
      <li><b>EIGHT (8, NUMBER_8)</b><br/>The '8' key at the top of the keyboard (not the number pad).</li>
      <li><b>NINE (9, NUMBER_9)</b><br/>The '9' key at the top of the keyboard (not the number pad).</li>
   </ul>
   
   <h3>Letter Keys</h3>
   
   <ul>
      <li><b>A</b><br/>The A key.</li>
      <li><b>B</b><br/>The B key.</li>
      <li><b>C</b><br/>The C key.</li>
      <li><b>D</b><br/>The D key.</li>
      <li><b>E</b><br/>The E key.</li>
      <li><b>F</b><br/>The F key.</li>
      <li><b>G</b><br/>The G key.</li>
      <li><b>H</b><br/>The H key.</li>
      <li><b>I</b><br/>The I key.</li>
      <li><b>J</b><br/>The J key.</li>
      <li><b>K</b><br/>The K key.</li>
      <li><b>L</b><br/>The L key.</li>
      <li><b>M</b><br/>The M key.</li>
      <li><b>N</b><br/>The N key.</li>
      <li><b>O</b><br/>The O key.</li>
      <li><b>P</b><br/>The P key.</li>
      <li><b>Q</b><br/>The Q key.</li>
      <li><b>R</b><br/>The R key.</li>
      <li><b>S</b><br/>The S key.</li>
      <li><b>T</b><br/>The T key.</li>
      <li><b>U</b><br/>The U key.</li>
      <li><b>V</b><br/>The V key.</li>
      <li><b>W</b><br/>The W key.</li>
      <li><b>X</b><br/>The X key.</li>
      <li><b>Y</b><br/>The Y key.</li>
      <li><b>Z</b><br/>The Z key.</li>
   </ul>
   
   <h3>Number Pad Keys</h3>
   
   <ul>   
      <li><b>NUM0 (NUMPAD_0)</b><br/>Zero on the number pad.</li>
      <li><b>NUM1 (NUMPAD_1)</b><br/>One on the number pad.</li>
      <li><b>NUM2 (NUMPAD_2)</b><br/>Two on the number pad.</li>
      <li><b>NUM3 (NUMPAD_3)</b><br/>Three on the number pad.</li>
      <li><b>NUM4 (NUMPAD_4)</b><br/>Four on the number pad.</li>
      <li><b>NUM5 (NUMPAD_5)</b><br/>Five on the number pad.</li>
      <li><b>NUM6 (NUMPAD_6)</b><br/>Six on the number pad.</li>
      <li><b>NUM7 (NUMPAD_7)</b><br/>Seven on the number pad.</li>
      <li><b>NUM8 (NUMPAD_8)</b><br/>Eight on the number pad.</li>
      <li><b>NUM9 (NUMPAD_9)</b><br/>Nine on the number pad.</li>
      <li><b>MULTIPLY (ASTERISK, NUMMULTIPLY, NUMPAD_MULTIPLY)</b><br/>The asterisk key on the number pad (*).</li>
      <li><b>ADD (NUMADD, NUMPAD_ADD)</b><br/>The add key on the number pad (+).</li>
      <li><b>SUBTRACT (NUMSUBTRACT, NUMPAD_SUBTRACT)</b><br/>The subtract key on the number pad (-).</li>
      <li><b>DECIMAL (NUMDECIMAL, NUMPERIOD, NUMPAD_DECIMAL, NUMPAD_PERIOD)</b><br/>The decimal key on the number pad (.).</li>
      <li><b>DIVIDE (NUMDIVIDE, NUMPAD_DIVIDE)</b><br/>The divide key on the number pad (/).</li>
      <li><b>NUMENTER (NUMPAD_ENTER)</b><br/>The enter key on the number pad.</li>
   </ul>
   
   <h3>Function Keys</h3>
   
   <ul>
      <li><b>F1</b><br/>The first function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F2</b><br/>The second function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F3</b><br/>The third function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F4</b><br/>The fourth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F5</b><br/>The fifth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F6</b><br/>The sixth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F7</b><br/>The seventh function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F8</b><br/>The eighth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F9</b><br/>The ninth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F11</b><br/>The eleventh function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F12</b><br/>The twelfth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F13</b><br/>The thirteenth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F14</b><br/>The fourteenth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
      <li><b>F15</b><br/>The fifteenth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.</li>
   </ul>
   
   <h3>Punctuation Keys</h3>
   
   <ul>
      <li><b>PLUS (EQUAL)</b><br/>The equals key (=). This is not the add key on the number pad.</li>
      <li><b>MINUS (UNDERSCORE)</b><br/>The minus key (-). This is not the subtract key on the number pad.</li>
      <li><b>COLON (SEMICOLON)</b><br/>The semi-colon key (;).</li>
      <li><b>COMMA (LESS_THAN)</b><br/>The comma key (,).</li>
      <li><b>PERIOD (GREATER_THAN)</b><br/>The period key (.). This is not the decimal on the number pad.</li>
      <li><b>BACKSLASH (QUESTION_MARK)</b><br/>The backslash key (/). This is not the divid key on the number pad.</li>
      <li><b>SLASH (FORWARD_SLASH, PIPE)</b><br/>The forward slash key (\).</li>
      <li><b>TILDE (BACKQUOTE)</b><br/>The tilde key (~).</li>
      <li><b>LEFT_BRACKET (LEFT_BRACE)</b><br/>The left bracket key ([).</li>
      <li><b>RIGHT_BRACKET (RIGHT_BRACE)</b><br/>The right bracket key (]).</li>
      <li><b>QUOTE</b><br/>The quote key (').</li>
   </ul>
   
   <h3>Other Keys</h3>
   
   <ul>
      <li><b>BACKSPACE</b><br/>The backspace key. Labeled 'delete' on Apple keyboards.</li>
      <li><b>TAB</b><br/>The tab key.</li>
      <li><b>SPACE (SPACE_BAR)</b><br/>The space bar key.</li>
      <li><b>ENTER (RETURN)</b><br/>The enter key. Labeled 'return' on Apple keyboards. This is not the enter key on the number pad.</li>
      <li><b>SHIFT</b><br/>Either the left or right shift key.</li>
      <li><b>CONTROL</b><br/>Either the left or right control key.</li>
      <li><b>COMMAND</b><br/>The command key. Only available on OSX.</li>
      <li><b>ALT (OPTION, ALTERNATE)</b><br/>The alt key. Labeled 'option' on Apple keyboards.</li>
      <li><b>PAUSE</b><br/>The pause key. Sometimes this is labeled 'break'.</li>
      <li><b>ESCAPE</b><br/>The escape key.</li>
      <li><b>INSERT</b><br/>The insert key.</li>
      <li><b>DELETE</b><br/>The delete key. This is the forward delete key on Apple keyboards.</li>
      <li><b>CAPS_LOCK</b><br/>The caps lock key.</li>
      <li><b>NUM_LOCK</b><br/>The num lock key.</li>
      <li><b>SCROLL_LOCK</b><br/>The scroll lock key.</li>
   </ul>
   
   <h3>Mouse</h3>
   
   <ul>
      <li><b>MOUSE_BUTTON</b><br/>The left mouse button.</li>
      <li><b>MOUSE_X</b><br/>Horizontal mouse movement.</li>
      <li><b>MOUSE_Y</b><br/>Vertical mouse movement.</li>
   </ul>
   
   </div>
</body>
</html>